COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	PCREF is a cross-referencing program for PASCAL source files,
C00005 00003	<HOW TO USE IT>
C00007 00004	<SWITCHES>
C00019 00005	<READING THE OUTPUT>
C00024 ENDMK
C⊗;
PCREF is a cross-referencing program for PASCAL source files,
useful also to obtain statement count listings (PROFILE in SAIL)
and to find omitted or excessive BEGINS and ENDS.

comments, gripes and bugs to ARR

<INPUT AND OUTPUT>

INPUT:
-----
through the file OLDSOURCE, a PASCAL source program file.

OUTPUT:
------

trough  the file CROSSLIST:
   1. If there is a file in your area with the name of your source and
	the extension .KNT:
	(a) A prettyprinted version of the program, showing in the left
	    margin the relations between BEGIN..END pairs, THEN..ELSE
	    pairs, etc, and showing a statement count of the execution,
	    similar to the flow counts of the ALGOLW compilers, that is,
	    counts for each basic block (group of statements with no branches)
	(b) if requested by switches, any of the other listings indicated
		below.
   2. If such a file is not found:
	(a) a prettyprinted version of the program, showing in the left
	    margin the relations between BEGIN..END pairs,THEN..ELSE
	    pairs, etc.
	(b) a cross reference of all the identifiers
	(c) a report of procedure and function declaration nesting.
	(d) a report of procedure and function call nesting.

By default, PCREF will change all reserved words and strings to upper
case, comments and everything else to lower case. There are switches 
available to change this condition.
<HOW TO USE IT>
You can:
	(a) use the /CREF switch when .EXECUTEing your
	     program, or calling .R PASCAL or .R PASSGO, or
	(b) call it directly by typing .R PCROSS.

In the first case, PCROSS will be called immediately after compilation.

	.r pcref				AND	.exec myprog(cref)
	OLDSOURCE= myprog.pas/nodots
	CROSSLIST=	<CR>

The left one calls it directly. The right one is a call through the compiler,
which will use the default options. The switches have to be spelled correctly.

The program parameters all have dafault values, but they can be modified
if desired, by the use of switches. See the subtopic SWITCHES.
<SWITCHES>
					Brackets indicate optional.
   					<n> stands for an integer number.
   					<L> stands for a letter.

   Switch	   Meaning					Default.

        FILES.
/CROSS[:<n>]  	writting of the crosslist file.              	on,15
                 <n> is the sum of:
                       1   source program listing
                       2   listing of identifiers
                       4   listing of proc-func
                           declaration nesting.
                       8   listing of proc-func call nesting.
/VERSION:<N>    behave as if conditionally compilinf %<N>
                comments.                                      -1
     
        PAGE AND LINE FORMAT
/WIDTH:<N>      maximum line length in CROSSLIST               132,120 (LOTS,SAIL)
/INDENT:<N>     indentation between levels.                    4,3 (LOTS,SAIL)
/INCREMENT:<N>  line number increment                          100

/[NO]DOTS       put as a guide a dotted line at the left
                margin every fifth line                        on
/[NO]HEAD	break the file in pages with headers for print on
/LINES:<N>      number of lines per page                       57,51 (LOTS,SAIL)
     
        STATEMENT FORMAT
/BEGIN:[-]<n>   if the [-] is not there, the contents of a
                  begin..end block is indented n spaces further.
                if it is there, the block will not be indented,
                  but the begin and end statements will be
                  exdented n spaces.                           0
/[NO]FORCE      forces newline in standard places. (before and
                 after begin, end, then, else, repeat, etc.)   off
     
        UPPER AND LOWER CASE
                       note: the possible values for <l> are:
                               u means upper case
                               l means lower case.
     
/RES:<l>        case used for reserved words.                  u
/NONRES:<l>     same for non-reserved words.                   l
/COMM:<l>       same for comments.                             l
/STR:<l>        same for strings.                              u
/CASE:<l>       resets all the defaults to <l>.                        off

--------

	NOTE: IF A FILE .KNT IS FOUND, THE STATEMENT COUNTS FROM 
		PROFILING THE PROGRAM WILL BE INSERTED, AND THE
		DEFAULT OF THE NEXT SWITCHES WILL CHANGE:

	/CROSS	1
	/FORCE	ON

<READING THE OUTPUT>

The cross-reference file CROSSLIST contains 4 parts:

1. THE PROGRAM LISTING:
	the letters and numbers in the left margin indicate the presence
	of reserved words which have to match. (BEGIN-END, etc.) The two
	words that match accorde with the scope rules will have the
	same number. The first one (e. g., BEGIN) will appear at left, and
	the second one (e.g., END) at right, inside the margin. The meaning
	of the letters is:
		B  Begin	E end
		I  If		T  Then		S Else
		L  Loop		X  Exit		E End
		C  Case		E  End
		R  Repeat	U  Until
	if a file with extension .KNT exists, it will take
	information from that file and include some counts on the left margin,
	right after the line numbers. Each number in this column indicates
	the number of times that the basic block that starts in that line
	was executed. Basic block is a sequence of statements with no branches
	(No IFs, GOTOs, or changes of looping scope. WITH does not start a
	Basic Block.).


2. THE CROSS REFERENCE LISTING OF IDENTIFIERS:
	It is ordered alphabetically. For each identifier it contains:
	    a. A 'P' or 'F' if it is a procedure or function, respectively.
	    b. The name of the identifier, up to 10 symbols.
	    c. The line numbers in which it occur. Those lines in which
		  it is declared are marked with a D; those in which it
		  occurs more than once are marked with an M (Multiple).

3. THE NESTING OF PROCEDURE-FUNCTION DECLARATION:
	It describes the static links. The scope is shown by indentation.
	Each line describes a procedure or function and contains:
	    a. The name.
	    b. an (M), (P) or (F) if it is the main program, a procedure
		  or a function, respectively.
	    c. If there are more than one procedure-function with the same
		  name (in different scopes, which is perfectly valid, but
		  a horrible thing to do), a D  (for DOUBLE) appears next,
		  and the rest of the information in this and the next part
		  of the listing contains data on both (or all of them, if
		  there are more than one.).
	    d. If it is an external procedure, an E will appear next.
	    e. The line number where the header appeared.
	    f. The line number of the BEGIN statement.
	    g. The line number of the END statement.

4. THE NESTING OF PROCEDURE-FUNCTION CALLS:
	It describes the dynamic links. Calling depth is indicated by 
	indenting. The format of each line is the same as in the previous
	report, except for the following:
	    a. Lines are numbered.
	    b. A procedure can be called from more than one place. To avoid
		repeating the list of proc-funcs called by it,an asterisk
		is printed after the name to indicate that it has already
		been 'described'. Instead of the line numbers for its
		appearence in the program, that for its appearence in this
		part of the listing is given, so that you can refer to it.